home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / misc / volume24 / gnucalc / part52 < prev    next >
Encoding:
Text File  |  1991-11-02  |  55.5 KB  |  1,304 lines

  1. Newsgroups: comp.sources.misc
  2. From: daveg@synaptics.com (David Gillespie)
  3. Subject:  v24i100:  gnucalc - GNU Emacs Calculator, v2.00, Part52/56
  4. Message-ID: <1991Nov3.001107.19867@sparky.imd.sterling.com>
  5. X-Md4-Signature: 00b5266219e8700dca42990e322ca57d
  6. Date: Sun, 3 Nov 1991 00:11:07 GMT
  7. Approved: kent@sparky.imd.sterling.com
  8.  
  9. Submitted-by: daveg@synaptics.com (David Gillespie)
  10. Posting-number: Volume 24, Issue 100
  11. Archive-name: gnucalc/part52
  12. Environment: Emacs
  13. Supersedes: gmcalc: Volume 13, Issue 27-45
  14.  
  15. #!/bin/sh
  16. # do not concatenate these parts, unpack them in order with /bin/sh
  17. # file calc.texinfo continued
  18. #
  19. if test ! -r _shar_seq_.tmp; then
  20.     echo 'Please unpack part 1 first!'
  21.     exit 1
  22. fi
  23. (read Scheck
  24.  if test "$Scheck" != 52; then
  25.     echo Please unpack part "$Scheck" next!
  26.     exit 1
  27.  else
  28.     exit 0
  29.  fi
  30. ) < _shar_seq_.tmp || exit 1
  31. if test ! -f _shar_wnt_.tmp; then
  32.     echo 'x - still skipping calc.texinfo'
  33. else
  34. echo 'x - continuing file calc.texinfo'
  35. sed 's/^X//' << 'SHAR_EOF' >> 'calc.texinfo' &&
  36. X
  37. @kindex Z E
  38. @pindex calc-user-define-edit
  39. @cindex Editing user definitions
  40. The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition
  41. of a user key.  This works for keys that have been defined by either
  42. keyboard macros or formulas; further details are contained in the relevant
  43. following sections.
  44. X
  45. @node Keyboard Macros, Invocation Macros, Creating User Keys, Programming
  46. @section Programming with Keyboard Macros
  47. X
  48. @noindent
  49. @kindex X
  50. @cindex Programming with keyboard macros
  51. @cindex Keyboard macros
  52. The easiest way to ``program'' the Emacs Calculator is to use standard
  53. keyboard macros.  Press @kbd{C-x (} to begin recording a macro.  From
  54. this point on, keystrokes you type will be saved away as well as
  55. performing their usual functions.  Press @kbd{C-x )} to end recording.
  56. Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to
  57. execute your keyboard macro by replaying the recorded keystrokes.
  58. @xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further
  59. information.@refill
  60. X
  61. When you use @kbd{X} to invoke a keyboard macro, the entire macro is
  62. treated as a single command by the undo and trail features.  The stack
  63. display buffer is not updated during macro execution, but is instead
  64. fixed up once the macro completes.  Thus, commands defined with keyboard
  65. macros are convenient and efficient.  The @kbd{C-x e} command, on the
  66. other hand, invokes the keyboard macro with no special treatment: Each
  67. command in the macro will record its own undo information and trail entry,
  68. and update the stack buffer accordingly.  If your macro uses features
  69. outside of Calc's control to operate on the contents of the Calc stack
  70. buffer, or if it includes Undo, Redo, or last-arguments commands, you
  71. must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date
  72. at all times.  You could also consider using @kbd{K} (@code{calc-keep-args})
  73. instead of @kbd{M-@key{RET}} (@code{calc-last-args}).
  74. X
  75. Calc extends the standard Emacs keyboard macros in several ways.
  76. Keyboard macros can be used to create user-defined commands.  Keyboard
  77. macros can include conditional and iteration structures, somewhat
  78. analogous to those provided by a traditional programmable calculator.
  79. X
  80. @menu
  81. * Naming Keyboard Macros::
  82. * Conditionals in Macros::
  83. * Loops in Macros::
  84. * Local Values in Macros::
  85. * Queries in Macros::
  86. @end menu
  87. X
  88. @node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros
  89. @subsection Naming Keyboard Macros
  90. X
  91. @noindent
  92. @kindex Z K
  93. @pindex calc-user-define-kbd-macro
  94. Once you have defined a keyboard macro, you can bind it to a @kbd{z}
  95. key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command.
  96. This command prompts first for a key, then for a command name.  For
  97. example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will
  98. define a keyboard macro which negates the top two numbers on the stack
  99. (@key{TAB} swaps the top two stack elements).  Now you can type
  100. @kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key
  101. sequence.  The default command name (if you answer the second prompt with
  102. just the @key{RET} key as in this example) will be something like
  103. @samp{calc-User-n}.  The keyboard macro will now be available as both
  104. @kbd{z n} and @kbd{M-x calc-User-n}.  You can backspace and enter a more
  105. descriptive command name if you wish.@refill
  106. X
  107. Macros defined by @kbd{Z K} act like single commands; they are executed
  108. in the same way as by the @kbd{X} key.  If you wish to define the macro
  109. as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}),
  110. give a negative prefix argument to @kbd{Z K}.
  111. X
  112. Once you have bound your keyboard macro to a key, you can use
  113. @kbd{Z P} to register it permanently with Emacs.  @xref{Creating User Keys}.
  114. X
  115. @cindex Keyboard macros, editing
  116. The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has
  117. been defined by a keyboard macro tries to use the @code{edit-kbd-macro}
  118. command to edit the macro.  This command may be found in the
  119. @file{macedit} package, a copy of which comes with Calc.  It decomposes
  120. the macro definition into full Emacs command names, like @code{calc-pop}
  121. and @code{calc-add}.  Type @kbd{M-# M-#} to finish editing and update
  122. the definition stored on the key, or, to cancel the edit, type
  123. @kbd{M-# x}.@refill
  124. X
  125. If you give a negative numeric prefix argument to @kbd{Z E}, the keyboard
  126. macro is edited in spelled-out keystroke form.  For example, the editing
  127. buffer might contain the nine characters @samp{1 RET 2 +}.  When you press
  128. @kbd{M-# M-#}, the @code{read-kbd-macro} feature of the @file{macedit}
  129. package is used to reinterpret these key names.  The
  130. notations @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL}, and
  131. @code{NUL} must be written in all uppercase, as must the prefixes @code{C-}
  132. and @code{M-}.  Spaces and line breaks are ignored.  Other characters are
  133. copied verbatim into the keyboard macro.  Basically, the notation is the
  134. same as is used in all of this manual's examples, except that the manual
  135. takes some liberties with spaces:  When we say @kbd{' [1 2 3] RET}, we take
  136. it for granted that it is clear we really mean @kbd{' [1 SPC 2 SPC 3] RET},
  137. which is what @code{read-kbd-macro} wants to see.@refill
  138. X
  139. If @file{macedit} is not available, @kbd{Z E} edits the keyboard macro
  140. in ``raw'' form; the editing buffer simply contains characters like
  141. @samp{1^M2+} (here @samp{^M} represents the carriage-return character).
  142. Editing in this mode, you will have to use @kbd{C-q} to enter more
  143. control characters into the buffer.@refill
  144. X
  145. @node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros
  146. @subsection Conditionals in Keyboard Macros
  147. X
  148. @noindent
  149. @kindex Z [
  150. @kindex Z :
  151. @kindex Z |
  152. @kindex Z ]
  153. @pindex calc-kbd-if
  154. @pindex calc-kbd-else
  155. @pindex calc-kbd-else-if
  156. @pindex calc-kbd-end-if
  157. @cindex Conditional structures
  158. The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if})
  159. commands allow you to put simple tests in a keyboard macro.  When Calc
  160. sees the @kbd{Z [}, it pops an object from the stack and, if the object is
  161. a non-zero value, continues executing keystrokes.  But if the object is
  162. zero, or if it is not provably nonzero, Calc skips ahead to the matching
  163. @kbd{Z ]} keystroke.  @xref{Logical Operations}, for a set of commands for
  164. performing tests which conveniently produce 1 for true and 0 for false.
  165. X
  166. For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value
  167. function in the form of a keyboard macro.  To program this macro, type
  168. @kbd{C-x (},
  169. type the above sequence of keystrokes, then type @kbd{C-x )}.  Note that
  170. the keystrokes will be executed while you are making the definition as
  171. well as when you later re-execute the macro by typing @kbd{X}.  Thus you
  172. should make sure a suitable number is on the stack before defining the
  173. macro so that you don't get a stack-underflow error during the
  174. definition process.@refill
  175. X
  176. The above macro duplicates the number on the top of the stack, pushes
  177. zero and compares using @kbd{a <} (@code{calc-less-than}), then, if
  178. the number was less than zero, executes @kbd{n} (@code{calc-change-sign}).
  179. Otherwise, the change-sign command is skipped.
  180. X
  181. Conditionals can be nested arbitrarily.  However, there should be exactly
  182. one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro.
  183. X
  184. The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between
  185. two keystroke sequences.  The general format is @kbd{@var{cond} Z [
  186. @var{then-part} Z : @var{else-part} Z ]}.  If @var{cond} is true
  187. (i.e., if the top of stack contains a non-zero number after @var{cond}
  188. has been executed), the @var{then-part} will be executed and the
  189. @var{else-part} will be skipped.  Otherwise, the @var{then-part} will
  190. be skipped and the @var{else-part} will be executed.
  191. X
  192. The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose
  193. between any number of alternatives.  For example,
  194. @kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z :
  195. @var{part3} Z ]} will execute @var{part1} if @var{cond1} is true,
  196. otherwise it will execute @var{part2} if @var{cond2} is true, otherwise
  197. it will execute @var{part3}.
  198. X
  199. More precisely, @kbd{Z [} pops a number and conditionally skips to the
  200. next matching @kbd{Z :} or @kbd{Z ]} key.  @kbd{Z ]} has no effect when
  201. actually executed.  @kbd{Z :} skips to the next matching @kbd{Z ]}.
  202. @kbd{Z |} pops a number and conditionally skips to the next matching
  203. @kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally
  204. equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |}
  205. does not.
  206. X
  207. Calc's conditional and looping constructs work by scanning the
  208. keyboard macro for occurrences of character sequences like @samp{Z:}
  209. and @samp{Z]}.  One side-effect of this is that if you use these
  210. constructs you must be careful that these character pairs do not
  211. occur by accident in other parts of the macros.  Since Calc rarely
  212. uses shift-Z for any purpose except as a prefix character, this is
  213. not likely to be a problem.  Another side-effect is that it will
  214. not work to define your own custom key bindings for these commands.
  215. Only the standard shift-Z bindings will work correctly.
  216. X
  217. The conditional and looping constructs are not actually tied to
  218. keyboard macros, but they are most often used in that context.
  219. For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push
  220. ten copies of 23 onto the stack.  This can be typed ``live'' just
  221. as easily as in a macro definition.
  222. X
  223. @kindex Z C-g
  224. If Calc gets stuck while skipping characters during the definition of a
  225. macro, type @kbd{Z C-g} to cancel the definition.  (Typing plain @kbd{C-g}
  226. actually adds a @kbd{C-g} keystroke to the macro.)
  227. X
  228. @node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros
  229. @subsection Loops in Keyboard Macros
  230. X
  231. @noindent
  232. @kindex Z <
  233. @kindex Z >
  234. @pindex calc-kbd-repeat
  235. @pindex calc-kbd-end-repeat
  236. @cindex Looping structures
  237. @cindex Iterative structures
  238. The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >}
  239. (@code{calc-kbd-end-repeat}) commands pop a number from the stack,
  240. which must be an integer, then repeat the keystrokes between the brackets
  241. the specified number of times.  If the integer is zero or negative, the
  242. body is skipped altogether.  For example, @kbd{1 @key{TAB} Z < 2 * Z >}
  243. computes two to a nonnegative integer power.  First, we push 1 on the
  244. stack and then swap the integer argument back to the top.  The @kbd{Z <}
  245. pops that argument leaving the 1 back on top of the stack.  Then, we
  246. repeat a multiply-by-two step however many times.@refill
  247. X
  248. Once again, the keyboard macro is executed as it is being entered.
  249. In this case it is especially important to set up reasonable initial
  250. conditions before making the definition:  Suppose the integer 1000 just
  251. happened to be sitting on the stack before we typed the above definition!
  252. Another approach is to enter a harmless dummy definition for the macro,
  253. then go back and edit in the real one with a @kbd{Z E} command.  Yet
  254. another approach is to type the macro as written-out keystroke names
  255. in a buffer, then use @kbd{M-# m} (@code{read-kbd-macro}) to read the
  256. macro.
  257. X
  258. @kindex Z /
  259. @pindex calc-break
  260. The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out
  261. of a keyboard macro loop prematurely.  It pops an object from the stack;
  262. if that object is true (a non-zero number), control jumps out of the
  263. innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues
  264. after the @kbd{Z >}.  If the object is false, the @kbd{Z /} has no
  265. effect.  Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;}
  266. in the C language.@refill
  267. X
  268. @kindex Z (
  269. @kindex Z )
  270. @pindex calc-kbd-for
  271. @pindex calc-kbd-end-for
  272. The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for})
  273. commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the
  274. value of the counter available inside the loop.  The general layout is
  275. @kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}.  The @kbd{Z (}
  276. command pops initial and final values from the stack.  It then creates
  277. a temporary internal counter and initializes it with the value @var{init}.
  278. The @kbd{Z (} command then repeatedly pushes the counter value onto the
  279. stack and executes @var{body} and @var{step}, adding @var{step} to the
  280. counter each time until the loop finishes.@refill
  281. X
  282. @cindex Summations (by keyboard macros)
  283. By default, the loop finishes when the counter becomes greater than (or
  284. less than) @var{final}, assuming @var{initial} is less than (greater
  285. than) @var{final}.  If @var{initial} is equal to @var{final}, the body
  286. executes exactly once.  The body of the loop always executes at least
  287. once.  For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the
  288. squares of the integers from 1 to 10, in steps of 1.
  289. X
  290. If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is
  291. forced to use upward-counting conventions.  In this case, if @var{initial}
  292. is greater than @var{final} the body will not be executed at all.
  293. Note that @var{step} may still be negative in this loop; the prefix
  294. argument merely constrains the loop-finished test.  Likewise, a prefix
  295. argument of @i{-1} forces downward-counting conventions.
  296. X
  297. @kindex Z @{
  298. @kindex Z @}
  299. @pindex calc-kbd-loop
  300. @pindex calc-kbd-end-loop
  301. The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}}
  302. (@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and
  303. @kbd{Z >}, except that they do not pop a count from the stack---they
  304. effectively create an infinite loop.  Every @kbd{Z @{} @dots{} @kbd{Z @}}
  305. loop ought to include at least one @kbd{Z /} to make sure the loop
  306. doesn't run forever.  (If any error message occurs which causes Emacs
  307. to beep, the keyboard macro will also be halted; this is a standard
  308. feature of Emacs.  You can also generally press @kbd{C-g} to halt a
  309. running keyboard macro, although not all versions of Unix support
  310. this feature.)
  311. X
  312. @xref{Conditionals in Macros}, for some additional notes about
  313. conditional and looping commands.
  314. X
  315. @node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros
  316. @subsection Local Values in Macros
  317. X
  318. @noindent
  319. @cindex Local variables
  320. @cindex Restoring saved modes
  321. Keyboard macros sometimes want to operate under known conditions
  322. without affecting surrounding conditions.  For example, a keyboard
  323. macro may wish to turn on Fraction Mode, or set a particular
  324. precision, independent of the user's normal setting for those
  325. modes.
  326. X
  327. @kindex Z `
  328. @kindex Z '
  329. @pindex calc-kbd-push
  330. @pindex calc-kbd-pop
  331. Macros also sometimes need to use local variables.  Assignments to
  332. local variables inside the macro should not affect any variables
  333. outside the macro.  The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '}
  334. (@code{calc-kbd-pop}) commands give you both of these capabilities.
  335. X
  336. When you type @kbd{Z `} (with a backquote or accent grave character),
  337. the values of various mode settings are saved away.  The ten ``quick''
  338. variables @code{q0} through @code{q9} are also saved.  When
  339. you type @kbd{Z '} (with an apostrophe), these values are restored.
  340. Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested.
  341. X
  342. If a keyboard macro halts due to an error in between a @kbd{Z `} and
  343. a @kbd{Z '}, the saved values will be restored correctly even though
  344. the macro never reaches the @kbd{Z '} command.  Thus you can use
  345. @kbd{Z `} and @kbd{Z '} without having to worry about what happens
  346. in exceptional conditions.
  347. X
  348. If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts
  349. you into a ``recursive edit.''  You can tell you are in a recursive
  350. edit because there will be extra square brackets in the mode line,
  351. as in @samp{[(Calculator)]}.  These brackets will go away when you
  352. type the matching @kbd{Z '} command.  The modes and quick variables
  353. will be saved and restored in just the same way as if actual keyboard
  354. macros were involved.
  355. X
  356. The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision
  357. and word size, the angular mode (Deg, Rad, or HMS), the simplification
  358. mode, the matrix mapping direction, Algebraic mode, Symbolic mode,
  359. Infinite mode, Matrix or Scalar mode, Fraction mode, and the current
  360. complex mode (Polar or Rectangular).  The ten ``quick'' variables'
  361. values (or lack thereof) are also saved.
  362. X
  363. Most mode-setting commands act as toggles, but with a numeric prefix
  364. they force the mode either on (positive prefix) or off (negative
  365. or zero prefix).  Since you don't know what the environment might
  366. be when you invoke your macro, it's best to use prefix arguments
  367. for all mode-setting commands inside the macro.
  368. X
  369. In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes
  370. listed above to their default values.  As usual, the matching @kbd{Z '}
  371. will restore the modes to their settings from before the @kbd{C-u Z `}.
  372. Also, @kbd{Z `} with a negative prefix argument resets the mapping
  373. direction and algebraic mode to their defaults but leaves the other
  374. modes the same as their values outside the construct.
  375. X
  376. The contents of the stack and trail, values of non-quick variables, and
  377. other settings such as the language mode and the various display modes,
  378. are @emph{not} affected by @kbd{Z `} and @kbd{Z '}.
  379. X
  380. @node Queries in Macros, , Local Values in Macros, Keyboard Macros
  381. @subsection Queries in Keyboard Macros
  382. X
  383. @noindent
  384. @kindex Z =
  385. @pindex calc-kbd-report
  386. The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative
  387. message including the value on the top of the stack.  You are prompted
  388. to enter a string.  That string, along with the top-of-stack value,
  389. is displayed unless @kbd{m w} (@code{calc-working}) has been used
  390. to turn such messages off.
  391. X
  392. @kindex Z #
  393. @pindex calc-kbd-query
  394. The @kbd{Z #} (@code{calc-kbd-query}) command displays a prompt message
  395. (which you enter during macro definition), then does an algebraic entry
  396. which takes its input from the keyboard, even during macro execution.
  397. This command allows your keyboard macros to accept numbers or formulas
  398. as interactive input.  All the normal conventions of algebraic input,
  399. including the use of @kbd{$} characters, are supported.
  400. @xref{Kbd Macro Query, , , emacs, the Emacs Manual}, for a description of
  401. @kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept
  402. keyboard input during a keyboard macro.  In particular, you can use
  403. @kbd{C-x q} to enter a recursive edit, which allows the user to perform
  404. any Calculator operations interactively before pressing @kbd{C-M-c} to
  405. return control to the keyboard macro.
  406. X
  407. @node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming
  408. @section Invocation Macros
  409. X
  410. @kindex M-# z
  411. @kindex Z I
  412. @pindex calc-user-invocation
  413. @pindex calc-user-define-invocation
  414. Calc provides one special keyboard macro, called up by @kbd{M-# z}
  415. (@code{calc-user-invocation}), that is intended to allow you to define
  416. your own special way of starting Calc.  To define this ``invocation
  417. macro,'' create the macro in the usual way with @kbd{C-x (} and
  418. @kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}).
  419. There is only one invocation macro, so you don't need to type any
  420. additional letters after @kbd{Z I}.  From now on, you can type
  421. @kbd{M-# z} at any time to execute your invocation macro.
  422. X
  423. For example, suppose you find yourself often grabbing rectangles of
  424. numbers into Calc and multiplying their columns.  You can do this
  425. by typing @kbd{M-# r} to grab, and @kbd{V R : *} to multiply columns.
  426. To make this into an invocation macro, just type @kbd{C-x ( M-# r
  427. V R : * C-x )}, then @kbd{Z I}.  Then, to multiply a rectangle of data,
  428. just mark the data in its buffer in the usual way and type @kbd{M-# z}.
  429. X
  430. Invocation macros are treated like regular Emacs keyboard macros;
  431. all the special features described above for @kbd{Z K}-style macros
  432. to not apply.  @kbd{M-# z} is just like @kbd{C-x e}, except that it
  433. uses the macro that was last stored by @kbd{Z I}.  (In fact, the
  434. macro does not even have to have anything to do with Calc!)
  435. X
  436. The @kbd{m m} command saves the last invocation macro defined by
  437. @kbd{Z I} along with all the other Calc mode settings.
  438. @xref{General Mode Commands}.
  439. X
  440. @node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming
  441. @section Programming with Formulas
  442. X
  443. @noindent
  444. @kindex Z F
  445. @pindex calc-user-define-formula
  446. @cindex Programming with algebraic formulas
  447. Another way to create a new Calculator command uses algebraic formulas.
  448. The @kbd{Z F} (@code{calc-user-define-formula}) command stores the
  449. formula at the top of the stack as the definition for a key.  This
  450. command prompts for five things: The key, the command name, the function
  451. name, the argument list, and the behavior of the command when given
  452. non-numeric arguments.
  453. X
  454. For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula
  455. @samp{a + 2*b} onto the stack.  We now type @kbd{Z F m} to define this
  456. formula on the @kbd{z m} key sequence.  The next prompt is for a command
  457. name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form
  458. for the new command.  If you simply press @key{RET}, a default name like
  459. @code{calc-User-m} will be constructed.  In our example, suppose we enter
  460. @kbd{spam @key{RET}} to define the new command as @code{calc-spam}.
  461. X
  462. If you want to give the formula a long-style name only, you can press
  463. @key{SPC} or @key{RET} when asked which single key to use.  For example
  464. @kbd{Z F @key{RET} spam @key{RET}} defines the new command as
  465. @kbd{M-x calc-spam}, with no keyboard equivalent.
  466. X
  467. The third prompt is for a function name.  The default is to use the same
  468. name as the command name but with @samp{calcFunc-} in place of
  469. @samp{calc-}.  This is the name you will use if you want to enter your
  470. new function in an algebraic formula.  Suppose we enter @kbd{yow @key{RET}}.
  471. Then the new function can be invoked by pushing two numbers on the
  472. stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic
  473. formula @samp{yow(x,y)}.@refill
  474. X
  475. The fourth prompt is for the function's argument list.  This is used to
  476. associate values on the stack with the variables that appear in the formula.
  477. The default is a list of all variables which appear in the formula, sorted
  478. into alphabetical order.  In our case, the default would be @samp{(a b)}.
  479. This means that, when the user types @kbd{z m}, the Calculator will remove
  480. two numbers from the stack, substitute these numbers for @samp{a} and
  481. @samp{b} (respectively) in the formula, then simplify the formula and
  482. push the result on the stack.  In other words, @kbd{10 @key{RET} 100 z m}
  483. would replace the 10 and 100 on the stack with the number 210, which is
  484. @cite{a + 2 b} with @cite{a=10} and @cite{b=100}.  Likewise, the formula
  485. @samp{yow(10, 100)} will be evaluated by substituting @cite{a=10} and
  486. @cite{b=100} in the definition.
  487. X
  488. You can rearrange the order of the names before pressing @key{RET} to
  489. control which stack positions go to which variables in the formula.  If
  490. you remove a variable from the argument list, that variable will be left
  491. in symbolic form by the command.  Thus using an argument list of @samp{(b)}
  492. for our function would cause @kbd{10 z m} to replace the 10 on the stack
  493. with the formula @samp{a + 20}.  If we had used an argument list of
  494. @samp{(b a)}, the result with inputs 10 and 100 would have been 120.
  495. X
  496. You can also put a nameless function on the stack instead of just a
  497. formula, as in @samp{<a, b : a + 2 b>}.  @xref{Specifying Operators}.
  498. In this example, the command will be defined by the formula @samp{a + 2 b}
  499. using the argument list @samp{(a b)}.
  500. X
  501. The final prompt is a y-or-n question concerning what to do if symbolic
  502. arguments are given to your function.  If you answer @kbd{y}, then
  503. executing @kbd{z m} (using the original argument list @samp{(a b)}) with
  504. arguments @cite{10} and @cite{x} will leave the function in symbolic
  505. form, i.e., @samp{yow(10,x)}.  On the other hand, if you answer @kbd{n},
  506. then the formula will always be expanded, even for non-constant
  507. arguments: @samp{10 + 2 x}.  If you never plan to feed algebraic
  508. formulas to your new function, it doesn't matter how you answer this
  509. question.@refill
  510. X
  511. If you answered @kbd{y} to this question you can still cause a function
  512. call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}).
  513. Also, Calc will expand the function if necessary when you take a
  514. derivative or integral or solve an equation involving the function.
  515. X
  516. @kindex Z G
  517. @pindex calc-get-user-defn
  518. Once you have defined a formula on a key, you can retrieve this formula
  519. with the @kbd{Z G} (@code{calc-user-define-get-defn}) command.  Press a
  520. key, and this command pushes the formula that was used to define that
  521. key onto the stack.  Actually, it pushes a nameless function that
  522. specifies both the argument list and the defining formula.  You will get
  523. an error message if the key is undefined, or if the key was not defined
  524. by a @kbd{Z F} command.@refill
  525. X
  526. The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has
  527. been defined by a formula uses a variant of the @code{calc-edit} command
  528. to edit the defining formula.  Press @kbd{M-# M-#} to finish editing and
  529. store the new formula back in the definition, or @kbd{M-# x} to
  530. cancel the edit.  (The argument list and other properties of the
  531. definition are unchanged; to adjust the argument list, you can use
  532. @kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and
  533. then re-execute the @kbd{Z F} command.)
  534. X
  535. As usual, the @kbd{Z P} command records your definition permanently.
  536. In this case it will permanently record all three of the relevant
  537. definitions: the key, the command, and the function.
  538. X
  539. You may find it useful to turn off the default simplifications with
  540. @kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be
  541. used as a function definition.  For example, the formula @samp{deriv(a^2,v)}
  542. which might be used to define a new function @samp{dsqr(a,v)} will be
  543. ``simplified'' to 0 immediately upon entry since @code{deriv} considers
  544. @cite{a} to be constant with respect to @cite{v}.  Turning off
  545. default simplifications cures this problem: the definition will be stored
  546. in symbolic form without ever activating the @code{deriv} function.  Press
  547. @kbd{m D} to turn the default simplifications back on afterwards.
  548. X
  549. @node Lisp Definitions, , Algebraic Definitions, Programming
  550. @section Programming with Lisp
  551. X
  552. @noindent
  553. The Calculator can be programmed quite extensively in Lisp.  All you
  554. do is write a normal Lisp function definition, but with @code{defmath}
  555. in place of @code{defun}.  This has the same form as @code{defun}, but it
  556. automagically replaces calls to standard Lisp functions like @code{+} and
  557. @code{zerop} with calls to the corresponding functions in Calc's own library.
  558. Thus you can write natural-looking Lisp code which operates on all of the
  559. standard Calculator data types.  You can then use @kbd{Z D} if you wish to
  560. bind your new command to a @kbd{z}-prefix key sequence.  The @kbd{Z E} command
  561. will not edit a Lisp-based definition.
  562. X
  563. Emacs Lisp is described in the GNU Emacs Lisp Reference Manual.  This section
  564. assumes a familiarity with Lisp programming concepts; if you do not know
  565. Lisp, you may find keyboard macros or rewrite rules to be an easier way
  566. to program the Calculator.
  567. X
  568. This section first discusses ways to write commands, functions, or
  569. small programs to be executed inside of Calc.  Then it discusses how
  570. your own separate programs are able to call Calc from the outside.
  571. Finally, there is a list of internal Calc functions and data structures
  572. for the true Lisp enthusiast.
  573. X
  574. @menu
  575. * Defining Functions::
  576. * Defining Simple Commands::
  577. * Defining Stack Commands::
  578. * Argument Qualifiers::
  579. * Example Definitions::
  580. X
  581. * Calling Calc from Your Programs::
  582. * Internals::
  583. @end menu
  584. X
  585. @node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions
  586. @subsection Defining New Functions
  587. X
  588. @noindent
  589. @findex defmath
  590. The @code{defmath} function (actually a Lisp macro) is like @code{defun}
  591. except that code in the body of the definition can make use of the full
  592. range of Calculator data types.  The prefix @samp{calcFunc-} is added
  593. to the specified name to get the actual Lisp function name.  As a simple
  594. example,
  595. X
  596. @example
  597. (defmath myfact (n)
  598. X  (if (> n 0)
  599. X      (* n (myfact (1- n)))
  600. X    1))
  601. @end example
  602. X
  603. @noindent
  604. This actually expands to the code,
  605. X
  606. @example
  607. (defun calcFunc-myfact (n)
  608. X  (if (math-posp n)
  609. X      (math-mul n (calcFunc-myfact (math-add n -1)))
  610. X    1))
  611. @end example
  612. X
  613. @noindent
  614. This function can be used in algebraic expressions, e.g., @samp{myfact(5)}.
  615. X
  616. The @samp{myfact} function as it is defined above has the bug that an
  617. expression @samp{myfact(a+b)} will be simplified to 1 because the
  618. formula @samp{a+b} is not considered to be @code{posp}.  A robust
  619. factorial function would be written along the following lines:
  620. X
  621. @smallexample
  622. (defmath myfact (n)
  623. X  (if (> n 0)
  624. X      (* n (myfact (1- n)))
  625. X    (if (= n 0)
  626. X        1
  627. X      nil)))    ; this could be simplified as: (and (= n 0) 1)
  628. @end smallexample
  629. X
  630. If a function returns @code{nil}, it is left unsimplified by the Calculator
  631. (except that its arguments will be simplified).  Thus, @samp{myfact(a+1+2)}
  632. will be simplified to @samp{myfact(a+3)} but no further.  Beware that every
  633. time the Calculator reexamines this formula it will attempt to resimplify
  634. it, so your function ought to detect the returning-@code{nil} case as
  635. efficiently as possible.
  636. X
  637. The following standard Lisp functions are treated by @code{defmath}:
  638. @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or
  639. @code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=},
  640. @code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor},
  641. @code{logandc2}, @code{lognot}.  Also, @code{~=} is an abbreviation for
  642. @code{math-nearly-equal}, which is useful in implementing Taylor series.@refill
  643. X
  644. For other functions @var{func}, if a function by the name
  645. @samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the
  646. name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself
  647. is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is
  648. used on the assumption that this is a to-be-defined math function.  Also, if
  649. the function name is quoted as in @samp{('integerp a)} the function name is
  650. always used exactly as written (but not quoted).@refill
  651. X
  652. Variable names have @samp{var-} prepended to them unless they appear in
  653. the function's argument list or in an enclosing @code{let}, @code{let*},
  654. @code{for}, or @code{foreach} form,
  655. or their names already contain a @samp{-} character.  Thus a reference to
  656. @samp{foo} is the same as a reference to @samp{var-foo}.@refill
  657. X
  658. A few other Lisp extensions are available in @code{defmath} definitions:
  659. X
  660. @itemize @bullet
  661. @item
  662. The @code{elt} function accepts any number of index variables.
  663. Note that Calc vectors are stored as Lisp lists whose first
  664. element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields
  665. the second element of vector @code{v}, and @samp{(elt m i j)}
  666. yields one element of a Calc matrix.
  667. X
  668. @item
  669. The @code{setq} function has been extended to act like the Common
  670. Lisp @code{setf} function.  (The name @code{setf} is recognized as
  671. a synonym of @code{setq}.)  Specifically, the first argument of
  672. @code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form,
  673. in which case the effect is to store into the specified
  674. element of a list.  Thus, @samp{(setq (elt m i j) x)} stores @cite{x}
  675. into one element of a matrix.
  676. X
  677. @item
  678. A @code{for} looping construct is available.  For example,
  679. @samp{(for ((i 0 10)) body)} executes @code{body} once for each
  680. binding of @cite{i} from zero to 10.  This is like a @code{let}
  681. form in that @cite{i} is temporarily bound to the loop count
  682. without disturbing its value outside the @code{for} construct.
  683. Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)},
  684. are also available.  For each value of @cite{i} from zero to 10,
  685. @cite{j} counts from 0 to @cite{i-1} in steps of two.  Note that
  686. @code{for} has the same general outline as @code{let}, except
  687. that each element of the header is a list of three or four
  688. things, not just two.
  689. X
  690. @item
  691. The @code{foreach} construct loops over elements of a list.
  692. For example, @samp{(foreach ((x (cdr v))) body)} executes
  693. @code{body} with @cite{x} bound to each element of Calc vector
  694. @cite{v} in turn.  The purpose of @code{cdr} here is to skip over
  695. the initial @code{vec} symbol in the vector.
  696. X
  697. @item
  698. The @code{break} function breaks out of the innermost enclosing
  699. @code{while}, @code{for}, or @code{foreach} loop.  If given a
  700. value, as in @samp{(break x)}, this value is returned by the
  701. loop.  (Lisp loops otherwise always return @code{nil}.)
  702. X
  703. @item
  704. The @code{return} function prematurely returns from the enclosing
  705. function.  For example, @samp{(return (+ x y))} returns @samp{x+y}
  706. as the value of a function.  You can use @code{return} anywhere
  707. inside the body of the function.
  708. @end itemize
  709. X
  710. Non-integer numbers (and extremely large integers) cannot be included
  711. directly into a @code{defmath} definition.  This is because the Lisp
  712. reader will fail to parse them long before @code{defmath} ever gets control.
  713. Instead, use the notation, @samp{:"3.1415"}.  In fact, any algebraic
  714. formula can go between the quotes.  For example,
  715. X
  716. @smallexample
  717. (defmath sqexp (x)     ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5)
  718. X  (and (numberp x)
  719. X       (exp :"x * 0.5")))
  720. @end smallexample
  721. X
  722. expands to
  723. X
  724. @smallexample
  725. (defun calcFunc-sqexp (x)
  726. X  (and (math-numberp x)
  727. X       (calcFunc-exp (math-mul x '(float 5 -1)))))
  728. @end smallexample
  729. X
  730. Note the use of @code{numberp} as a guard to ensure that the argument is
  731. a number first, returning @code{nil} if not.  The exponential function
  732. could itself have been included in the expression, if we had preferred:
  733. @samp{:"exp(x * 0.5)"}.  As another example, the multiplication-and-recursion
  734. step of @code{myfact} could have been written
  735. X
  736. @example
  737. :"n * myfact(n-1)"
  738. @end example
  739. X
  740. If a file named @file{.emacs} exists in your home directory, Emacs reads
  741. and executes the Lisp forms in this file as it starts up.  While it may
  742. seem like a good idea to put your favorite @code{defmath} commands here,
  743. this has the unfortunate side-effect that parts of the Calculator must be
  744. loaded in to process the @code{defmath} commands whether or not you will
  745. actually use the Calculator!  A better effect can be had by writing
  746. X
  747. @example
  748. (put 'calc-define 'thing '(progn
  749. X (defmath ... )
  750. X (defmath ... )
  751. ))
  752. @end example
  753. X
  754. @noindent
  755. @vindex calc-define
  756. The @code{put} function adds a @dfn{property} to a symbol.  Each Lisp
  757. symbol has a list of properties associated with it.  Here we add a
  758. property with a name of @code{thing} and a @samp{(progn ...)} form as
  759. its value.  When Calc starts up, and at the start of every Calc command,
  760. the property list for the symbol @code{calc-define} is checked and the
  761. values of any properties found are evaluated as Lisp forms.  The
  762. properties are removed as they are evaluated.  The property names
  763. (like @code{thing}) are not used; you should choose something like the
  764. name of your project so as not to conflict with other properties.
  765. X
  766. The net effect is that you can put the above code in your @file{.emacs}
  767. file and it will not be executed until Calc is loaded.  Or, you can put
  768. that same code in another file which you load by hand either before or
  769. after Calc itself is loaded.
  770. X
  771. The properties of @code{calc-define} are evaluated in the same order
  772. that they were added.  They can assume that the Calc modules @file{calc.el},
  773. @file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and
  774. that the @samp{*Calculator*} buffer will be the current buffer.
  775. X
  776. If your @code{calc-define} property only defines algebraic functions,
  777. you can be sure that it will have been evaluated before Calc tries to
  778. call your function, even if the file defining the property is loaded
  779. after Calc is loaded.  But if the property defines commands or key
  780. sequences, it may not be evaluated soon enough.  (Suppose it defines the
  781. new command @code{tweak-calc}; the user can load your file, then type
  782. @kbd{M-x tweak-calc} before Calc has had chance to do anything.)  To
  783. protect against this situation, you can put
  784. X
  785. @example
  786. (run-hooks 'calc-check-defines)
  787. @end example
  788. X
  789. @findex calc-check-defines
  790. @noindent
  791. at the end of your file.  The @code{calc-check-defines} function is what
  792. looks for and evaluates properties on @code{calc-define}; @code{run-hooks}
  793. has the advantage that it is quietly ignored if @code{calc-check-defines}
  794. is not yet defined because Calc has not yet been loaded.
  795. X
  796. Examples of things that ought to be enclosed in a @code{calc-define}
  797. property are @code{defmath} calls, @code{define-key} calls that modify
  798. the Calc key map, and any calls that redefine things defined inside Calc.
  799. Ordinary @code{defun}s need not be enclosed with @code{calc-define}.
  800. X
  801. @node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions
  802. @subsection Defining New Simple Commands
  803. X
  804. @noindent
  805. @findex interactive
  806. If a @code{defmath} form contains an @code{interactive} clause, it defines
  807. a Calculator command.  Actually such a @code{defmath} results in @emph{two}
  808. function definitions:  One, a @samp{calcFunc-} function as was just described,
  809. with the @code{interactive} clause removed.  Two, a @samp{calc-} function
  810. with a suitable @code{interactive} clause and some sort of wrapper to make
  811. the command work in the Calc environment.
  812. X
  813. In the simple case, the @code{interactive} clause has the same form as
  814. for normal Emacs Lisp commands:
  815. X
  816. @smallexample
  817. (defmath increase-precision (delta)
  818. X  "Increase precision by DELTA."     ; This is the "documentation string"
  819. X  (interactive "p")                  ; Register this as a M-x-able command
  820. X  (setq calc-internal-prec (+ calc-internal-prec delta)))
  821. @end smallexample
  822. X
  823. This expands to the pair of definitions,
  824. X
  825. @smallexample
  826. (defun calc-increase-precision (delta)
  827. X  "Increase precision by DELTA."
  828. X  (interactive "p")
  829. X  (calc-wrapper
  830. X   (setq calc-internal-prec (math-add calc-internal-prec delta))))
  831. X
  832. (defun calcFunc-increase-precision (delta)
  833. X  "Increase precision by DELTA."
  834. X  (setq calc-internal-prec (math-add calc-internal-prec delta)))
  835. @end smallexample
  836. X
  837. @noindent
  838. where in this case the latter function would never really be used!  Note
  839. that since the Calculator stores small integers as plain Lisp integers,
  840. the @code{math-add} function will work just as well as the native
  841. @code{+} even when the intent is to operate on native Lisp integers.
  842. X
  843. @findex calc-wrapper
  844. The @samp{calc-wrapper} call invokes a macro which surrounds the body of
  845. the function with code that looks like this:
  846. X
  847. @smallexample
  848. X  (let ((calc-command-flags nil))
  849. X    (unwind-protect
  850. X        (progn
  851. X          (save-excursion
  852. X            (calc-select-buffer)
  853. X            @emph{body of function})
  854. X          (calc-finish-command))
  855. X      (calc-cleanup-command)))
  856. @end smallexample
  857. X
  858. @findex calc-select-buffer
  859. The @code{calc-select-buffer} function selects the @samp{*Calculator*}
  860. buffer if necessary, say, because the command was invoked from inside
  861. the @samp{*Calc Trail*} window.
  862. X
  863. @findex calc-finish-command
  864. The @code{calc-finish-command} function recomputes the line numbers
  865. for all stack entries if they have been changed.
  866. Also, if the @code{clear-message} flag is set
  867. it executes @samp{(message "")} to clear any lingering ``Working'' message
  868. out of the echo area.@refill
  869. X
  870. @findex calc-cleanup-command
  871. The @code{calc-cleanup-command} function normally aligns the stack window
  872. so that the top element of the stack is visible at the
  873. bottom of the window, and moves the cursor down to the bottom line.
  874. This can be suppressed by setting the @code{no-align}
  875. flag as described below.  Also, it clears the Inverse and Hyperbolic
  876. flags (unless the @code{keep-flags} flag has been set), and updates the
  877. display of the mode line.@refill
  878. X
  879. @findex calc-set-command-flag
  880. You can call, for example, @code{(calc-set-command-flag 'no-align)} to set
  881. the above-mentioned command flags.  The following command flags are
  882. recognized by Calc routines:
  883. X
  884. @table @code
  885. @item renum-stack
  886. Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered
  887. after this command completes.  This is set by routines like
  888. @code{calc-push}.
  889. X
  890. @item clear-message
  891. Calc should call @samp{(message "")} if this command completes normally.
  892. X
  893. @item no-align
  894. Do not move the cursor back to the @samp{.} top-of-stack marker.
  895. X
  896. @item position-point
  897. Use the variables @code{calc-position-point-line} and
  898. @code{calc-position-point-column} to position the cursor after
  899. this command finishes.
  900. X
  901. @item keep-flags
  902. Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag},
  903. and @code{calc-keep-args-flag} at the end of this command.
  904. X
  905. @item do-edit
  906. Switch to buffer @samp{*Calc Edit*} after this command.
  907. @end table
  908. X
  909. @kindex Y
  910. @kindex Y ?
  911. @vindex calc-Y-help-msgs
  912. Calc reserves a special prefix key, shift-@kbd{Y}, for user-written
  913. extensions to Calc.  There are no built-in commands that work with
  914. this prefix key; you must call @code{define-key} from Lisp (probably
  915. from inside a @code{calc-define} property) to add to it.  Initially only
  916. @kbd{Y ?} is defined; it takes help messages from a list of strings
  917. (initially @code{nil}) in the variable @code{calc-Y-help-msgs}.  All
  918. other undefined keys except for @kbd{Y} are reserved for use by
  919. future versions of Calc.
  920. X
  921. If you are writing a Calc enhancement which you expect to give to
  922. others, it is best to minimize the number of @kbd{Y}-key sequences
  923. you use.  In fact, if you have more than one key sequence you should
  924. consider defining three-key sequences with @kbd{Y}, then a key that
  925. stands for your package, then a third key for the particular command
  926. within your package.
  927. X
  928. Users may wish to install several Calc enhancements, and it is possible
  929. that several enhancements will choose to use the same key.  In the
  930. example below, a variable @code{inc-prec-base-key} has been defined
  931. to contain the key that identifies the @code{inc-prec} package.  Its
  932. value is initially @code{"P"}, but a user can change this variable
  933. if necessary without having to modify the file.
  934. X
  935. Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I}
  936. command that increases the precision, and a @kbd{Y P D} command that
  937. decreases the precision.
  938. X
  939. @smallexample
  940. ;;; Increase and decrease Calc precision.  Dave Gillespie, 5/31/91.
  941. ;;; (Include copyright or copyleft stuff here.)
  942. X
  943. (defvar inc-prec-base-key "P"
  944. X  "Base key for inc-prec.el commands.")
  945. X
  946. (put 'calc-define 'inc-prec '(progn
  947. X
  948. (define-key calc-mode-map (format "Y%sI" inc-prec-base-key)
  949. X            'increase-precision)
  950. (define-key calc-mode-map (format "Y%sD" inc-prec-base-key)
  951. X            'decrease-precision)
  952. X
  953. (setq calc-Y-help-msgs
  954. X      (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key)
  955. X            calc-Y-help-msgs))
  956. X
  957. (defmath increase-precision (delta)
  958. X  "Increase precision by DELTA."
  959. X  (interactive "p")
  960. X  (setq calc-internal-prec (+ calc-internal-prec delta)))
  961. X
  962. (defmath decrease-precision (delta)
  963. X  "Decrease precision by DELTA."
  964. X  (interactive "p")
  965. X  (setq calc-internal-prec (- calc-internal-prec delta)))
  966. X
  967. ))  ; end of calc-define property
  968. X
  969. (run-hooks 'calc-check-defines)
  970. @end smallexample
  971. X
  972. @node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions
  973. @subsection Defining New Stack-Based Commands
  974. X
  975. @noindent
  976. To define a new computational command which takes and/or leaves arguments
  977. on the stack, a special form of @code{interactive} clause is used.
  978. X
  979. @example
  980. (interactive @var{num} @var{tag})
  981. @end example
  982. X
  983. @noindent
  984. where @var{num} is an integer, and @var{tag} is a string.  The effect is
  985. to pop @var{num} values off the stack, resimplify them by calling
  986. @code{calc-normalize}, and hand them to your function according to the
  987. function's argument list.  Your function may include @code{&optional} and
  988. @code{&rest} parameters, so long as calling the function with @var{num}
  989. parameters is legal.
  990. X
  991. Your function must return either a number or a formula in a form
  992. acceptable to Calc, or a list of such numbers or formulas.  These value(s)
  993. are pushed onto the stack when the function completes.  They are also
  994. recorded in the Calc Trail buffer on a line beginning with @var{tag},
  995. a string of (normally) four characters or less.  If you omit @var{tag}
  996. or use @code{nil} as a tag, the result is not recorded in the trail.
  997. X
  998. As an example, the definition
  999. X
  1000. @smallexample
  1001. (defmath myfact (n)
  1002. X  "Compute the factorial of the integer at the top of the stack."
  1003. X  (interactive 1 "fact")
  1004. X  (if (> n 0)
  1005. X      (* n (myfact (1- n)))
  1006. X    (and (= n 0) 1)))
  1007. @end smallexample
  1008. X
  1009. @noindent
  1010. is a version of the factorial function shown previously which can be used
  1011. as a command as well as an algebraic function.  It expands to
  1012. X
  1013. @smallexample
  1014. (defun calc-myfact ()
  1015. X  "Compute the factorial of the integer at the top of the stack."
  1016. X  (interactive)
  1017. X  (calc-slow-wrapper
  1018. X   (calc-enter-result 1 "fact"
  1019. X     (cons 'calcFunc-myfact (calc-top-list-n 1)))))
  1020. X
  1021. (defun calcFunc-myfact (n)
  1022. X  "Compute the factorial of the integer at the top of the stack."
  1023. X  (if (math-posp n)
  1024. X      (math-mul n (calcFunc-myfact (math-add n -1)))
  1025. X    (and (math-zerop n) 1)))
  1026. @end smallexample
  1027. X
  1028. @findex calc-slow-wrapper
  1029. The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper}
  1030. that automatically puts up a @samp{Working...} message before the
  1031. computation begins.  (This message can be turned off by the user
  1032. with an @kbd{m w} (@code{calc-working}) command.)
  1033. X
  1034. @findex calc-top-list-n
  1035. The @code{calc-top-list-n} function returns a list of the specified number
  1036. of values from the top of the stack.  It resimplifies each value by
  1037. calling @code{calc-normalize}.  If its argument is zero it returns an
  1038. empty list.  It does not actually remove these values from the stack.
  1039. X
  1040. @findex calc-enter-result
  1041. The @code{calc-enter-result} function takes an integer @var{num} and string
  1042. @var{tag} as described above, plus a third argument which is either a
  1043. Calculator data object or a list of such objects.  These objects are
  1044. resimplified and pushed onto the stack after popping the specified number
  1045. of values from the stack.  If @var{tag} is non-@code{nil}, the values
  1046. being pushed are also recorded in the trail.
  1047. X
  1048. Note that if @code{calcFunc-myfact} returns @code{nil} this represents
  1049. ``leave the function in symbolic form.''  To return an actual empty list,
  1050. in the sense that @code{calc-enter-result} will push zero elements back
  1051. onto the stack, you should return the special value @samp{'(nil)}, a list
  1052. containing the single symbol @code{nil}.
  1053. X
  1054. The @code{interactive} declaration can actually contain a limited
  1055. Emacs-style code string as well which comes just before @var{num} and
  1056. @var{tag}.  Currently the only Emacs code supported is @samp{"p"}, as in
  1057. X
  1058. @example
  1059. (defmath foo (a b &optional c)
  1060. X  (interactive "p" 2 "foo")
  1061. X  @var{body})
  1062. @end example
  1063. X
  1064. In this example, the command @code{calc-foo} will evaluate the expression
  1065. @samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if
  1066. executed with a numeric prefix argument of @cite{n}.
  1067. X
  1068. The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"}
  1069. code as used with @code{defun}).  It uses the numeric prefix argument as the
  1070. number of objects to remove from the stack and pass to the function.
  1071. In this case, the integer @var{num} serves as a default number of
  1072. arguments to be used when no prefix is supplied.
  1073. X
  1074. @node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions
  1075. @subsection Argument Qualifiers
  1076. X
  1077. @noindent
  1078. Anywhere a parameter name can appear in the parameter list you can also use
  1079. an @dfn{argument qualifier}.  Thus the general form of a definition is:
  1080. X
  1081. @example
  1082. (defmath @var{name} (@var{param} @var{param...}
  1083. X               &optional @var{param} @var{param...}
  1084. X               &rest @var{param})
  1085. X  @var{body})
  1086. @end example
  1087. X
  1088. @noindent
  1089. where each @var{param} is either a symbol or a list of the form
  1090. X
  1091. @example
  1092. (@var{qual} @var{param})
  1093. @end example
  1094. X
  1095. The following qualifiers are recognized:
  1096. X
  1097. @table @samp
  1098. @item complete
  1099. @findex complete
  1100. The argument must not be an incomplete vector, interval, or complex number.
  1101. (This is rarely needed since the Calculator itself will never call your
  1102. function with an incomplete argument.  But there is nothing stopping your
  1103. own Lisp code from calling your function with an incomplete argument.)@refill
  1104. X
  1105. @item integer
  1106. @findex integer
  1107. The argument must be an integer.  If it is an integer-valued float
  1108. it will be accepted but converted to integer form.  Non-integers and
  1109. formulas are rejected.
  1110. X
  1111. @item natnum
  1112. @findex natnum
  1113. Like @samp{integer}, but the argument must be non-negative.
  1114. X
  1115. @item fixnum
  1116. @findex fixnum
  1117. Like @samp{integer}, but the argument must fit into a native Lisp integer,
  1118. which on most systems means less than 2^23 in absolute value.  The
  1119. argument is converted into Lisp-integer form if necessary.
  1120. X
  1121. @item float
  1122. @findex float
  1123. The argument is converted to floating-point format if it is a number or
  1124. vector.  If it is a formula it is left alone.  (The argument is never
  1125. actually rejected by this qualifier.)
  1126. X
  1127. @item @var{pred}
  1128. The argument must satisfy predicate @var{pred}, which is one of the
  1129. standard Calculator predicates.  @xref{Predicates}.
  1130. X
  1131. @item not-@var{pred}
  1132. The argument must @emph{not} satisfy predicate @var{pred}.
  1133. @end table
  1134. X
  1135. For example,
  1136. X
  1137. @example
  1138. (defmath foo (a (constp (not-matrixp b)) &optional (float c)
  1139. X              &rest (integer d))
  1140. X  @var{body})
  1141. @end example
  1142. X
  1143. @noindent
  1144. expands to
  1145. X
  1146. @example
  1147. (defun calcFunc-foo (a b &optional c &rest d)
  1148. X  (and (math-matrixp b)
  1149. X       (math-reject-arg b 'not-matrixp))
  1150. X  (or (math-constp b)
  1151. X      (math-reject-arg b 'constp))
  1152. X  (and c (setq c (math-check-float c)))
  1153. X  (setq d (mapcar 'math-check-integer d))
  1154. X  @var{body})
  1155. @end example
  1156. X
  1157. @noindent
  1158. which performs the necessary checks and conversions before executing the
  1159. body of the function.
  1160. X
  1161. @node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions
  1162. @subsection Example Definitions
  1163. X
  1164. @noindent
  1165. This section includes some Lisp programming examples on a larger scale.
  1166. These programs make use of many of the Calculator's internal functions
  1167. (@pxref{Internals}).
  1168. X
  1169. @menu
  1170. * Sine Example::
  1171. @end menu
  1172. X
  1173. @node Sine Example, , Example Definitions, Example Definitions
  1174. @subsubsection The Sine Function
  1175. X
  1176. @noindent
  1177. A somewhat limited sine function could be defined as follows, using the
  1178. well-known Taylor series expansion for @samp{sin(x)}:
  1179. X
  1180. @smallexample
  1181. (defmath mysin ((float (anglep x)))
  1182. X  (interactive 1 "mysn")
  1183. X  (setq x (to-radians x))    ; Convert from current angular mode.
  1184. X  (let ((sum x)              ; Initial term of Taylor expansion of sin.
  1185. X        newsum
  1186. X        (nfact 1)            ; "nfact" equals "n" factorial at all times.
  1187. X        (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2.
  1188. X    (for ((n 3 100 2))       ; Upper limit of 100 is a good precaution.
  1189. X         (working "mysin" sum)   ; Display "Working" message, if enabled.
  1190. X         (setq nfact (* nfact (1- n) n)
  1191. X               x (* x xnegsqr)
  1192. X               newsum (+ sum (/ x nfact)))
  1193. X         (if (~= newsum sum)     ; If newsum is "nearly equal to" sum,
  1194. X             (break))            ;  then we are done.
  1195. X         (setq sum newsum))
  1196. X    sum))
  1197. @end smallexample
  1198. X
  1199. The actual @code{sin} function in Calc works by first reducing the problem
  1200. to a sine or cosine of a nonnegative number less than @c{$\pi \over 4$}
  1201. @cite{pi/4}.  This
  1202. ensures that the Taylor series will converge quickly.  Also, the calculation
  1203. is carried out with two extra digits of precision to guard against cumulative
  1204. round-off in @samp{sum}.  Finally, complex arguments are allowed and handled
  1205. by a separate algorithm.
  1206. X
  1207. @smallexample
  1208. (defmath mysin ((float (scalarp x)))
  1209. X  (interactive 1 "mysn")
  1210. X  (setq x (to-radians x))    ; Convert from current angular mode.
  1211. X  (with-extra-prec 2         ; Evaluate with extra precision.
  1212. X    (cond ((complexp x)
  1213. X           (mysin-complex x))
  1214. X          ((< x 0)
  1215. X           (- (mysin-raw (- x)))    ; Always call mysin-raw with x >= 0.
  1216. X          (t (mysin-raw x))))))
  1217. X
  1218. (defmath mysin-raw (x)
  1219. X  (cond ((>= x 7)
  1220. X         (mysin-raw (% x (two-pi))))     ; Now x < 7.
  1221. X        ((> x (pi-over-2))
  1222. X         (- (mysin-raw (- x (pi)))))     ; Now -pi/2 <= x <= pi/2.
  1223. X        ((> x (pi-over-4))
  1224. X         (mycos-raw (- x (pi-over-2))))  ; Now -pi/2 <= x <= pi/4.
  1225. X        ((< x (- (pi-over-4)))
  1226. X         (- (mycos-raw (+ x (pi-over-2)))))  ; Now -pi/4 <= x <= pi/4,
  1227. X        (t (mysin-series x))))           ; so the series will be efficient.
  1228. @end smallexample
  1229. X
  1230. @noindent
  1231. where @code{mysin-complex} is an appropriate function to handle complex
  1232. numbers, @code{mysin-series} is the routine to compute the sine Taylor
  1233. series as before, and @code{mycos-raw} is a function analogous to
  1234. @code{mysin-raw} for cosines.
  1235. X
  1236. The strategy is to ensure that @cite{x} is nonnegative before calling
  1237. @code{mysin-raw}.  This function then recursively reduces its argument
  1238. to a suitable range, namely, plus-or-minus @c{$\pi \over 4$}
  1239. @cite{pi/4}.  Note that each
  1240. test, and particularly the first comparison against 7, is designed so
  1241. that small roundoff errors cannnot produce an infinite loop.  (Suppose
  1242. we compared with @samp{(two-pi)} instead; if due to roundoff problems
  1243. the modulo operator ever returned @samp{(two-pi)} exactly, an infinite
  1244. recursion could result!)  We use modulo only for arguments that will
  1245. clearly get reduced, knowing that the next rule will catch any reductions
  1246. that this rule misses.
  1247. X
  1248. If a program is being written for general use, it is important to code
  1249. it carefully as shown in this second example.  For quick-and-dirty programs,
  1250. when you know that your own use of the sine function will never encounter
  1251. a large argument, a simpler program like the first one shown is fine.
  1252. X
  1253. @node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions
  1254. @subsection Calling Calc from Your Lisp Programs
  1255. X
  1256. @noindent
  1257. A later section (@pxref{Internals}) gives a full description of
  1258. Calc's internal Lisp functions.  It's not hard to call Calc from
  1259. inside your programs, but the number of these functions can be daunting.
  1260. So Calc provides one special ``programmer-friendly'' function called
  1261. @code{calc-eval} that can be made to do just about everything you
  1262. need.  It's not as fast as the low-level Calc functions, but it's
  1263. much simpler to use!
  1264. X
  1265. It may seem that @code{calc-eval} itself has a daunting number of
  1266. options, but they all stem from one simple operation.
  1267. X
  1268. In its simplest manifestation, @samp{(calc-eval "1+2")} parses the
  1269. string @samp{"1+2"} as if it were a Calc algebraic entry and returns
  1270. the result formatted as a string: @samp{"3"}.
  1271. X
  1272. Since @code{calc-eval} is on the list of recommended @code{autoload}
  1273. functions, you don't need to make any special preparations to load
  1274. Calc before calling @code{calc-eval} the first time.  Calc will be
  1275. loaded and initialized for you.
  1276. X
  1277. All the Calc modes that are currently in effect will be used when
  1278. evaluating the expression and formatting the result.
  1279. X
  1280. @ifinfo
  1281. @example
  1282. X
  1283. @end example
  1284. @end ifinfo
  1285. @subsubsection Additional Arguments to @code{calc-eval}
  1286. X
  1287. @noindent
  1288. If the input string parses to a list of expressions, Calc returns
  1289. the results separated by @samp{", "}.  You can specify a different
  1290. separator by giving a second string argument to @code{calc-eval}:
  1291. SHAR_EOF
  1292. true || echo 'restore of calc.texinfo failed'
  1293. fi
  1294. echo 'End of  part 52'
  1295. echo 'File calc.texinfo is continued in part 53'
  1296. echo 53 > _shar_seq_.tmp
  1297. exit 0
  1298. exit 0 # Just in case...
  1299. -- 
  1300. Kent Landfield                   INTERNET: kent@sparky.IMD.Sterling.COM
  1301. Sterling Software, IMD           UUCP:     uunet!sparky!kent
  1302. Phone:    (402) 291-8300         FAX:      (402) 291-4362
  1303. Please send comp.sources.misc-related mail to kent@uunet.uu.net.
  1304.